<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Class: ActiveRecord::ConnectionAdapters::TableDefinition</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Class</strong></td>
          <td class="class-name-in-header">ActiveRecord::ConnectionAdapters::TableDefinition</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../../files/vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions_rb.html">
                vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
                </a>
        <br />
            </td>
        </tr>

        <tr class="top-aligned-row">
            <td><strong>Parent:</strong></td>
            <td>
                <a href="../../Object.html">
                Object
               </a>
            </td>
        </tr>
        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Represents a SQL table in an abstract way. Columns are stored as a
ColumnDefinition in the columns attribute.
</p>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M001221">[]</a>&nbsp;&nbsp;
      <a href="#M001225">belongs_to</a>&nbsp;&nbsp;
      <a href="#M001222">column</a>&nbsp;&nbsp;
      <a href="#M001219">new</a>&nbsp;&nbsp;
      <a href="#M001220">primary_key</a>&nbsp;&nbsp;
      <a href="#M001224">references</a>&nbsp;&nbsp;
      <a href="#M001223">timestamps</a>&nbsp;&nbsp;
      <a href="#M001226">to_sql</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">





    <div id="attribute-list">
      <h3 class="section-bar">Attributes</h3>

      <div class="name-list">
        <table>
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">columns</td>
          <td class="context-item-value">&nbsp;[RW]&nbsp;</td>
          <td class="context-item-desc"></td>
        </tr>
        </table>
      </div>
    </div>
      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Class methods</h3>

      <div id="method-M001219" class="method-detail">
        <a name="M001219"></a>

        <div class="method-heading">
          <a href="#M001219" class="method-signature">
          <span class="method-name">new</span><span class="method-args">(base)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001219-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001219-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 278</span>
278:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">initialize</span>(<span class="ruby-identifier">base</span>)
279:         <span class="ruby-ivar">@columns</span> = []
280:         <span class="ruby-ivar">@base</span> = <span class="ruby-identifier">base</span>
281:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M001221" class="method-detail">
        <a name="M001221"></a>

        <div class="method-heading">
          <a href="#M001221" class="method-signature">
          <span class="method-name">[]</span><span class="method-args">(name)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a ColumnDefinition for the <a
href="TableDefinition.html#M001222">column</a> with name <tt>name</tt>.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001221-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001221-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 290</span>
290:       <span class="ruby-keyword kw">def</span> <span class="ruby-operator">[]</span>(<span class="ruby-identifier">name</span>)
291:         <span class="ruby-ivar">@columns</span>.<span class="ruby-identifier">find</span> {<span class="ruby-operator">|</span><span class="ruby-identifier">column</span><span class="ruby-operator">|</span> <span class="ruby-identifier">column</span>.<span class="ruby-identifier">name</span>.<span class="ruby-identifier">to_s</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">name</span>.<span class="ruby-identifier">to_s</span>}
292:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M001225" class="method-detail">
        <a name="M001225"></a>

        <div class="method-heading">
          <span class="method-name">belongs_to</span><span class="method-args">(*args)</span>
        </div>
      
        <div class="method-description">
          <p>
Alias for <a href="TableDefinition.html#M001224">references</a>
</p>
        </div>
      </div>

      <div id="method-M001222" class="method-detail">
        <a name="M001222"></a>

        <div class="method-heading">
          <a href="#M001222" class="method-signature">
          <span class="method-name">column</span><span class="method-args">(name, type, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Instantiates a <a href="TableDefinition.html#M001219">new</a> <a
href="TableDefinition.html#M001222">column</a> for the table. The
<tt>type</tt> parameter is normally one of the migrations native types,
which is one of the following: <tt>:<a
href="TableDefinition.html#M001220">primary_key</a></tt>, <tt>:string</tt>,
<tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>,
<tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>, <tt>:date</tt>,
<tt>:binary</tt>, <tt>:boolean</tt>.
</p>
<p>
You may use a type not in this list as long as it is supported by your
database (for example, &quot;polygon&quot; in MySQL), but this will not be
database agnostic and should usually be avoided.
</p>
<p>
Available options are (none of these exists by default):
</p>
<ul>
<li><tt>:limit</tt> - Requests a maximum <a
href="TableDefinition.html#M001222">column</a> length (<tt>:string</tt>,
<tt>:text</tt>, <tt>:binary</tt> or <tt>:integer</tt> columns only)

</li>
<li><tt>:default</tt> - The <a
href="TableDefinition.html#M001222">column</a>&#8216;s default value. Use
nil for NULL.

</li>
<li><tt>:null</tt> - Allows or disallows <tt>NULL</tt> values in the <a
href="TableDefinition.html#M001222">column</a>. This option could have been
named <tt>:null_allowed</tt>.

</li>
<li><tt>:precision</tt> - Specifies the precision for a <tt>:decimal</tt> <a
href="TableDefinition.html#M001222">column</a>.

</li>
<li><tt>:scale</tt> - Specifies the scale for a <tt>:decimal</tt> <a
href="TableDefinition.html#M001222">column</a>.

</li>
</ul>
<p>
Please be aware of different RDBMS implementations behavior with
<tt>:decimal</tt> columns:
</p>
<ul>
<li>The SQL standard says the default scale should be 0, <tt>:scale</tt> &lt;=
<tt>:precision</tt>, and makes no comments about the requirements of
<tt>:precision</tt>.

</li>
<li>MySQL: <tt>:precision</tt> [1..63], <tt>:scale</tt> [0..30]. Default is
(10,0).

</li>
<li>PostgreSQL: <tt>:precision</tt> [1..infinity], <tt>:scale</tt>
[0..infinity]. No default.

</li>
<li>SQLite2: Any <tt>:precision</tt> and <tt>:scale</tt> may be used. Internal
storage as strings. No default.

</li>
<li>SQLite3: No restrictions on <tt>:precision</tt> and <tt>:scale</tt>, but
the maximum supported <tt>:precision</tt> is 16. No default.

</li>
<li>Oracle: <tt>:precision</tt> [1..38], <tt>:scale</tt> [-84..127]. Default is
(38,0).

</li>
<li>DB2: <tt>:precision</tt> [1..63], <tt>:scale</tt> [0..62]. Default unknown.

</li>
<li>Firebird: <tt>:precision</tt> [1..18], <tt>:scale</tt> [0..18]. Default
(9,0). Internal types NUMERIC and DECIMAL have different storage rules,
decimal being better.

</li>
<li>FrontBase?: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0). WARNING Max <tt>:precision</tt>/<tt>:scale</tt> for NUMERIC is 19,
and DECIMAL is 38.

</li>
<li>SqlServer?: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0).

</li>
<li>Sybase: <tt>:precision</tt> [1..38], <tt>:scale</tt> [0..38]. Default
(38,0).

</li>
<li>OpenBase?: Documentation unclear. Claims storage in <tt>double</tt>.

</li>
</ul>
<p>
This method returns <tt>self</tt>.
</p>
<h2>Examples</h2>
<pre>
 # Assuming td is an instance of TableDefinition
 td.column(:granted, :boolean)
   #=&gt; granted BOOLEAN

 td.column(:picture, :binary, :limit =&gt; 2.megabytes)
   #=&gt; picture BLOB(2097152)

 td.column(:sales_stage, :string, :limit =&gt; 20, :default =&gt; 'new', :null =&gt; false)
   #=&gt; sales_stage VARCHAR(20) DEFAULT 'new' NOT NULL

 def.column(:bill_gates_money, :decimal, :precision =&gt; 15, :scale =&gt; 2)
   #=&gt; bill_gates_money DECIMAL(15,2)

 def.column(:sensor_reading, :decimal, :precision =&gt; 30, :scale =&gt; 20)
   #=&gt; sensor_reading DECIMAL(30,20)

 # While &lt;tt&gt;:scale&lt;/tt&gt; defaults to zero on most databases, it
 # probably wouldn't hurt to include it.
 def.column(:huge_integer, :decimal, :precision =&gt; 30)
   #=&gt; huge_integer DECIMAL(30)
</pre>
<h2>Short-hand examples</h2>
<p>
Instead of calling <a href="TableDefinition.html#M001222">column</a>
directly, you can also work with the short-hand definitions for the default
types. They use the type as the method name instead of as a parameter and
allow for multiple columns to be defined in a single statement.
</p>
<p>
What can be written like this with the regular calls to <a
href="TableDefinition.html#M001222">column</a>:
</p>
<pre>
  create_table &quot;products&quot;, :force =&gt; true do |t|
    t.column &quot;shop_id&quot;,    :integer
    t.column &quot;creator_id&quot;, :integer
    t.column &quot;name&quot;,       :string,   :default =&gt; &quot;Untitled&quot;
    t.column &quot;value&quot;,      :string,   :default =&gt; &quot;Untitled&quot;
    t.column &quot;created_at&quot;, :datetime
    t.column &quot;updated_at&quot;, :datetime
  end
</pre>
<p>
Can also be written as follows using the short-hand:
</p>
<pre>
  create_table :products do |t|
    t.integer :shop_id, :creator_id
    t.string  :name, :value, :default =&gt; &quot;Untitled&quot;
    t.timestamps
  end
</pre>
<p>
There&#8216;s a short-hand method for each of the type values declared at
the top. And then there&#8216;s <a
href="TableDefinition.html#M001223">TableDefinition#timestamps</a>
that&#8216;ll add created_at and updated_at as datetimes.
</p>
<p>
<a href="TableDefinition.html#M001224">TableDefinition#references</a> will
add an appropriately-named _id <a
href="TableDefinition.html#M001222">column</a>, plus a corresponding _type
<a href="TableDefinition.html#M001222">column</a> if the :polymorphic
option is supplied. If :polymorphic is a hash of options, these will be
used when creating the _type <a
href="TableDefinition.html#M001222">column</a>. So what can be written like
this:
</p>
<pre>
  create_table :taggings do |t|
    t.integer :tag_id, :tagger_id, :taggable_id
    t.string  :tagger_type
    t.string  :taggable_type, :default =&gt; 'Photo'
  end
</pre>
<p>
Can also be written as follows using <a
href="TableDefinition.html#M001224">references</a>:
</p>
<pre>
  create_table :taggings do |t|
    t.references :tag
    t.references :tagger, :polymorphic =&gt; true
    t.references :taggable, :polymorphic =&gt; { :default =&gt; 'Photo' }
  end
</pre>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001222-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001222-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 418</span>
418:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">column</span>(<span class="ruby-identifier">name</span>, <span class="ruby-identifier">type</span>, <span class="ruby-identifier">options</span> = {})
419:         <span class="ruby-identifier">column</span> = <span class="ruby-keyword kw">self</span>[<span class="ruby-identifier">name</span>] <span class="ruby-operator">||</span> <span class="ruby-constant">ColumnDefinition</span>.<span class="ruby-identifier">new</span>(<span class="ruby-ivar">@base</span>, <span class="ruby-identifier">name</span>, <span class="ruby-identifier">type</span>)
420:         <span class="ruby-identifier">column</span>.<span class="ruby-identifier">limit</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:limit</span>] <span class="ruby-operator">||</span> <span class="ruby-identifier">native</span>[<span class="ruby-identifier">type</span>.<span class="ruby-identifier">to_sym</span>][<span class="ruby-identifier">:limit</span>] <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:limit</span>] <span class="ruby-keyword kw">or</span> <span class="ruby-identifier">native</span>[<span class="ruby-identifier">type</span>.<span class="ruby-identifier">to_sym</span>]
421:         <span class="ruby-identifier">column</span>.<span class="ruby-identifier">precision</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:precision</span>]
422:         <span class="ruby-identifier">column</span>.<span class="ruby-identifier">scale</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:scale</span>]
423:         <span class="ruby-identifier">column</span>.<span class="ruby-identifier">default</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:default</span>]
424:         <span class="ruby-identifier">column</span>.<span class="ruby-identifier">null</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:null</span>]
425:         <span class="ruby-ivar">@columns</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">column</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-ivar">@columns</span>.<span class="ruby-identifier">include?</span> <span class="ruby-identifier">column</span>
426:         <span class="ruby-keyword kw">self</span>
427:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M001220" class="method-detail">
        <a name="M001220"></a>

        <div class="method-heading">
          <a href="#M001220" class="method-signature">
          <span class="method-name">primary_key</span><span class="method-args">(name)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Appends a primary key definition to the table definition. Can be called
multiple times, but this is probably not a good idea.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001220-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001220-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 285</span>
285:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">primary_key</span>(<span class="ruby-identifier">name</span>)
286:         <span class="ruby-identifier">column</span>(<span class="ruby-identifier">name</span>, <span class="ruby-identifier">:primary_key</span>)
287:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M001224" class="method-detail">
        <a name="M001224"></a>

        <div class="method-heading">
          <a href="#M001224" class="method-signature">
          <span class="method-name">references</span><span class="method-args">(*args)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001224-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001224-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 448</span>
448:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">references</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
449:         <span class="ruby-identifier">options</span> = <span class="ruby-identifier">args</span>.<span class="ruby-identifier">extract_options!</span>
450:         <span class="ruby-identifier">polymorphic</span> = <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>(<span class="ruby-identifier">:polymorphic</span>)
451:         <span class="ruby-identifier">args</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">col</span><span class="ruby-operator">|</span>
452:           <span class="ruby-identifier">column</span>(<span class="ruby-node">&quot;#{col}_id&quot;</span>, <span class="ruby-identifier">:integer</span>, <span class="ruby-identifier">options</span>)
453:           <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">polymorphic</span>.<span class="ruby-identifier">nil?</span>
454:             <span class="ruby-identifier">column</span>(<span class="ruby-node">&quot;#{col}_type&quot;</span>, <span class="ruby-identifier">:string</span>, <span class="ruby-identifier">polymorphic</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Hash</span>) <span class="ruby-operator">?</span> <span class="ruby-identifier">polymorphic</span> <span class="ruby-operator">:</span> {})
455:           <span class="ruby-keyword kw">end</span>
456:         <span class="ruby-keyword kw">end</span>
457:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M001223" class="method-detail">
        <a name="M001223"></a>

        <div class="method-heading">
          <a href="#M001223" class="method-signature">
          <span class="method-name">timestamps</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Appends <tt>:datetime</tt> columns <tt>:created_at</tt> and
<tt>:updated_at</tt> to the table.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001223-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001223-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 443</span>
443:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">timestamps</span>
444:         <span class="ruby-identifier">column</span>(<span class="ruby-identifier">:created_at</span>, <span class="ruby-identifier">:datetime</span>)
445:         <span class="ruby-identifier">column</span>(<span class="ruby-identifier">:updated_at</span>, <span class="ruby-identifier">:datetime</span>)
446:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M001226" class="method-detail">
        <a name="M001226"></a>

        <div class="method-heading">
          <a href="#M001226" class="method-signature">
          <span class="method-name">to_sql</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns a String whose contents are the <a
href="TableDefinition.html#M001222">column</a> definitions concatenated
together. This string can then be prepended and appended to to generate the
final SQL to create the table.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M001226-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M001226-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb, line 463</span>
463:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">to_sql</span>
464:         <span class="ruby-ivar">@columns</span> <span class="ruby-operator">*</span> <span class="ruby-value str">', '</span>
465:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>